// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.

using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.Data.Entity.Storage
{

    /// <summary>
    ///     <para>  
    ///         Creates and deletes databases for a given database provider.
    ///     </para>  
    ///     <para>  
    ///         This interface is typically used by database providers (and other extensions). It is generally  
    ///         not used in application code.  
    ///     </para>  
    /// </summary>
    public interface IDatabaseCreator
    {
        /// <summary>
        ///     <para>
        ///         Ensures that the database for the context does not exist. If it does not exist, no action is taken. If it does
        ///         exist then the database is deleted.
        ///     </para>
        ///     <para>
        ///         Warning: The entire database is deleted an no effort is made to remove just the database objects that are used by 
        ///         the model for this context.
        ///     </para>
        /// </summary>
        /// <returns> True if the database is deleted, false if it did not exist. </returns>
        bool EnsureDeleted();

        /// <summary>
        ///     <para>
        ///         Asynchronously ensures that the database for the context does not exist. If it does not exist, no action is taken. If it does
        ///         exist then the database is deleted.
        ///     </para>
        ///     <para>
        ///         Warning: The entire database is deleted an no effort is made to remove just the database objects that are used by 
        ///         the model for this context.
        ///     </para>
        /// </summary>
        /// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
        /// <returns> 
        ///     A task that represents the asynchronous save operation. The task result contains true if the database is deleted, 
        ///     false if it did not exist. 
        /// </returns>
        Task<bool> EnsureDeletedAsync(CancellationToken cancellationToken = default(CancellationToken));

        /// <summary>
        ///     Ensures that the database for the context exists. If it exists, no action is taken. If it does not
        ///     exist then the database and all its schema are created. If the database exists, then no effort is made
        ///     to ensure it is compatible with the model for this context.
        /// </summary>
        /// <returns> True if the database is created, false if it already existed. </returns>
        bool EnsureCreated();

        /// <summary>
        ///     Asynchronously ensures that the database for the context exists. If it exists, no action is taken. If it does not
        ///     exist then the database and all its schema are created. If the database exists, then no effort is made
        ///     to ensure it is compatible with the model for this context.
        /// </summary>
        /// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
        /// <returns> 
        ///     A task that represents the asynchronous save operation. The task result contains true if the database is created, 
        ///     false if it already existed. 
        /// </returns>
        Task<bool> EnsureCreatedAsync(CancellationToken cancellationToken = default(CancellationToken));
    }
}
